vSphere HTML Client SDK - Javascript API

  1. Overview
  2. Modal APIs
  3. Client Application APIs
  4. Event APIs

1. Overview

The vSphere HTML Client SDK offers a set of JavaScript APIs which facilitate the building of HTML Client-only plugins, fully compatible with the HTML-based vSphere Client. The JavaScript APIs may be used by the plugin to communicate with the HTML Client and to execute a number of operations. Each plugin will have access to the JavaScript APIs within its own iframe which eliminates the possibility of plugin conflicts. Please refer to the Plug-in Architecture Diagram in the online vSphere Client SDK documentation.

API Namespaces

The JavaScript APIs are organized in several domains depending on their functionality. This improves readability and communicates clearly the API functionality scope:

API Accessibility

The JavaScript APIs can be accessed by getting the API object directly from the extension's iframe, such as: window.frameElement.htmlClientSdk
In order to make the following examples more readable, we will use a shortcut for the JS API object, namely, "htmlSdk" which will be equal to "window.frameElement.htmlClientSdk"

Note: For practical examples on how to use the JS APIs, see the "html-sample" plugin.

2. Modal APIs

The modal APIs are used to perform various actions for a modal dialog such as open, close and configure. The modal APIs can be accessed with the window.frameElement.htmlClientSdk.modal.{API}

APIDescriptionExample usage
open(configObj) Opens a modal dialog and accepts for parameter a configuration object, which contains:

{
 url: string,
 title?: string,
 size?: {
  width: number,
  height: number
 };
 closable?: boolean;
 onClosed?: (result?: any) => void,
 contextObjects?: any[],
 customData?: any,
}
var config = {
 url: "chassisa/resources/editChassisDialog.html",
 title: "Edit Chassis",
 size: {
  width: 490,
  height: 240
 },
 onClosed: function(id) { alert("Modal " + id + " closed."); },
 contextObjects: [{ id: "urn:vri:samples:ChassisA:chassis-3" },
    { id: "urn:vri:samples:ChassisA:chassis-2" }],
 customData: {idsRange: [1, 9]}
 };

htmlSdk.modal.open(config);
close(data) Closes the already opened modal. The modal is the one corresponding to the iframe from which this API was called from.
If data has been provided it will be passed to the onClose callback function if such was specified in the parameter of the modal.open API 		var modalId = 2;
htmlSdk.modal.close(modalId);
setOptions(configObj) Changes the configuration of the modal with properties specified in the parameter object, which contains:

{
 title: string,
 height: number
} 		htmlSdk.modal.setOptions({
 title: "New Title",
 height: 450
});
getCustomData() Returns the custom data that was provided upon opening the modal through customData property htmlSdk.modal.getCustomData();

 for example: {idsRange: [1, 9]}

3. Client Application APIs

The client application APIs are related to the HTML Client application. The client application APIs can be accessed with the window.frameElement.htmlClientSdk.app.{API}

APIsDescriptionExample usage
getContextObjects() Returns current context objects:
  • In global views the result is empty because global views are not associated with any vSphere object
  • In views that are associated with a particular vSphere object the result contains a JavaScript object with a field named 'id' - the ID of the selected vSphere object
  • In modals opened through a SDK call to htmlSdk.modal.open(configObj) the result is the value of configObj.contextObjects or an empty array if configObj.contextObjects is undefined
  • In modals opened through actions defined in the plugin.xml file the result is an array of context objects representing the targets of the invoked action. Each context object is a JavaScript object that contains a field named 'id' which is the id of the corresponding target object.
    Note: the result will be an empty array if there are no target objects.
htmlSdk.app.getContextObjects();

 for example: { id: "urn:vri:samples:ChassisA:chassis-3" }
navigateTo(configObj) Navigates to a specified view with an optional custom data which will be passed to the view.
The configuration object should contain the following information:

{
 targetViewId: string,
 objectId?: string,
 customData?: any
}

When navigating to a global view, the "objectId" property can be skipped. 		htmlSdk.app.navigateTo({
 targetViewId: "com.vmware.samples.chassisa.summary",
 objectId: "urn:vri:samples:ChassisA:chassis-3",
 customData: {name: "test", filter: true}
});
getNavigationData() Retrieves the navigation data passed to the current view by the navigateTo() API.
If you have called:

htmlSdk.app.navigateTo({
 targetViewId: "com.vmware.samples.chassisa.summary",
 objectId: "urn:vri:samples:ChassisA:chassis-3",
 customData: {name: "test", filter: true}
});

Then, you can use:
htmlSdk.app.getNavigationData();

and you will get: {name: "test", filter: true}
getClientInfo() Returns information about the current vSphere Client, such as "version", "type" etc. htmlSdk.app.getClientInfo();

 for example: {type: "HTML", version: "6.5.1"}
getClientLocale() Returns the current locale of the vSphere Client htmlSdk.app.getClientLocale();

 for example: "de-DE"

5. Event APIs

The event APIs provide means for plugins to subscribe and respond to events. These APIs can be accessed via window.frameElement.htmlClientSdk.event.{API}

APIDescriptionExample usage
onGlobalRefresh(callbackFunction) Subscribes to a global refresh event and when such an event occurs, the callback function will be executed. function updateData() { alert("Data is updated after a global refresh."); }

htmlSdk.event.onGlobalRefresh(updateData);